.TH LIBPFM 3  "November, 2003" "" "Linux Programmer's Manual"
.SH NAME
pfm_get_pmu_name, pfm_get_pmu_type, pfm_get_pmu_name_bytype, pfm_pmu_is_supported, pfm_force_pmu,pfm_list_supported_pmu \- query library about supported PMU models
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.sp
.BI "int pfm_get_pmu_name(char *"name ", int " maxlen);
.BI "int pfm_get_pmu_type(int *" type);
.BI "int pfm_get_pmu_name_bytype(int " type ", char *" name ", int " maxlen);
.BI "int pfm_pmu_is_supported(int " type);
.BI "int pfm_force_pmu(int " type);
.BI "int pfm_list_supported_pmus(int (*" pf ")(const char *"fmt ",...));"
.sp
.SH DESCRIPTION
These functions retrieve information about the detected host PMU
and the PMU models supported by the library. More than one model
can be supported by the same library.

Each PMU model is assigned a type and a name. The latter is just
a string and the former is a unique identifier. The currently 
supported types are:
.TP
.B PFMLIB_GENERIC_PMU
the default architected PMU model, i.e., the basic model.
.TP
.B PFMLIB_ITANIUM_PMU
the Itanium processor PMU model. The model is found in the first
implementation of the IA-64 architecture, code name Merced.
.TP
.B PFMLIB_ITANIUM2_PMU
the Itanium 2 processor PMU model. This is the model provided
by McKinley, Madison, and Deerfield processors.
.LP
The \fBpfm_get_pmu_name\fR function returns the name of the detected 
host PMU. The library must have been initialized properly before making this
call. The name is returned in the \fBname\fR argument. The \fBmaxlen\fR argument 
indicates the maximum length of the buffer provided for \fBname\fR.
Up to \fBmaxlen-1\fR characters will be returned, not including the
termination character.

.sp
The \fBpfm_get_pmu_type\fR function returns the type of the detected host
PMU. The library must have been initialized properly before making this
call. The type returned in  \fBtype\fR can be any one of the three listed above. 
.sp
The \fBpfm_get_pmu_name_bytype\fR function returns the name of a PMU model in
\fBname\fR given a type in the \fBtype\fR argument. The \fBmaxlen\fR argument 
indicates the maximum length of the buffer provided for \fBname\fR.
Up to \fBmaxlen-1\fR characters will be returned, not including the
termination character.

.sp
The \fBpfm_pmu_is_supported\fR function returns \fBPFMLIB_SUCCESS\fR if the given
PMU type is supported by the library independently of what the host PMU model is.
.sp
The \fBpfm_force_pmu\fR function is used to forced the library to use a particular
PMU model compared to what it has detected. The library checks that the selected 
type can be supported by the host PMU. This is mostly useful to force the
library to the use generic PMU model \fBPFMLIB_GENERIC_PMU\fR.  This function can
be called at any time and upon return the library is considered initialized.
.sp
The \fBpfm_list_supported_pmu\fR function is used to print the list PMU types
that the library supports. The results is printed using the function provided
in the \fBpf\fR argument, which must be a printf-style function.
.SH RETURN
The function returns whether or not it was successful.
A return value of \fBPFMLIB_SUCCESS\fR indicates success, 
otherwise the value is the error code.
.SH ERRORS
.B PFMLIB_ERR_NOINIT
the library has not been initialized properly.
.TP
.B PFMLIB_ERR_INVAL
invalid argument was given, most likely invalid pointer or invalid PMU type.
.TP
.B PFMLIB_ERR_NOTSUPP
the selected PMU type can be used on the host CPU.
.SH AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
.PP
